Update v0.8 spec with updated catalog negotiation style by jacobsimionato · Pull Request #136 · google/A2UI

jacobsimionato · 2025-11-24T03:54:34Z

Summary of changes:

Replace clientUiCapabilities message type with a similar metadata parameter which is included in every message, rather than just once.
Resolve ambiguities in the schema, e.g. whether custom components are additive or not.
Add JSON schemas for key metadata fields etc.
Rename "dynamic catalogs" to "inline catalogs".

Fixes #135

specification/0.8/docs/a2ui_protocol.md

This reverts commit 7d0afbf.

This reverts commit 4b6062f.

jacobsimionato · 2025-11-27T04:22:51Z

Hey, I overhauled this based on your new proposal. PTAL!

wrenj · 2025-12-03T13:47:38Z

specification/0.8/docs/a2ui_extension_specification.md


-params.acceptsDynamicSchemas: (OPTIONAL) A boolean indicating if the agent can accept a clientUiCapabilities message containing a dynamicCatalog. If omitted, this defaults to false.
+#### Parameter Definitions
+- `params.acceptsInlineCatalogs`: (OPTIONAL) A boolean indicating if the agent can accept an `inlineCatalogs` array in the client's `a2uiClientCapabilities`. If omitted, this defaults to `false`.


single inline catalog right?

i see multiple below

whats the usecase you are envisioning here? not saying having an array is a problem just curious if it solves any problems not solved by a single inline catalog?

I can totally see an ecosystem of inline catalogs evolving, available to client developers to include in their clients. You could concatenate them, I suppose, but why not have a list?

the agent picks a single catalog to use, the inline catalogs aren't concatenated, so the client would say here are 3 inline catalogs pick one which I don't understand

My take 1. InlineCatalogs hopefully are only used in non-prod environments. The server agent permitting which catalog(s) in its agent card is the primary mechanism we should push for.
2. For inline catalogs, one can imagine client developers keeping separate catalog files for each of their components. If we support that, then both the server and client need to have a long list of catalogs to manage. The client could collate components off of each catalog and send the list inline.

I put multiple inline catalogs here because I figured it's consistent with advertising multiple well-known catalogs which an agent can pick from. If a client supports 5 different catalogs, shouldn't it also be able to advertise them all inline? Or should it have to pick only one of them to advertise inline, and advertise the rest only via ID?

Thinking about it a bit more, I can see how this is not especially likely to be used in practice, because how will agents know which catalog to pick? But I kind of still want to leave it here, because it doesn't add much complexity to the API, and I think it might even make the client SDKs simpler - you will just have a boolean like "advertiseCatalogsInline" rather than a setting which specific catalog of your many catalogs you'd like to advertise inline.

I agree with Mandar that this is mostly a mechanism for local development, so we don't have to think too hard about it.

How strongly does everyone feel? I'll remove this if there is consensus that it's overly complex!

I like it as a ~~list.~~ dictionary.

multiple inline catalogs sgtm

its not a list though its a dictionary right? of catalogId: inlineCatalogJson ?

Yes, you're right, it's a dict.

The catalog_description_schema contains catalogId already, which I think makes sense - a catalog should declare it's Id. Now, inlineCatalogs references this schema. So I think it makes sense to just have an array of these, and each of them has an ID in it, rather than redundantly including the ID as a key as well. Yes, there could be duplicate Ids, and that would be an error.

WDYT?

specification/0.8/docs/a2ui_extension_specification.md

wrenj · 2025-12-03T13:51:26Z

specification/0.8/docs/a2ui_protocol.md

 - `surfaceUpdate`: Provides a list of component definitions to be added to or updated in a specific UI area called a "surface."
 - `dataModelUpdate`: Provides new data to be inserted into or to replace a surface's data model. Each surface has its own data model.
- `beginRendering`: Signals to the client that it has enough information to perform the initial render, specifying the ID of the root component.
+- `beginRendering`: Signals to the client that it has enough information to perform the initial render, specifying the ID of the root component and, optionally, the component catalog to use.


I'd require it in begin render, or you could default it to the standard one

Why is the agent card option not sufficient here?

@wrenj Re requiring this: I want to add it as an optional parameter to beginRender in v0.8 and default to standard catalog, to make this change non-breaking. Otherwise all our agents theoretically need updating right away. In v0.9, let's make this required and explicit. I filed #193 for this.

@dmandar Re the switch I've made here to having the client advertise multiple catalogs and have the server choose, instead of the inverse - see https://docs.google.com/document/d/1SppqNwHytVIUp7o8x5py5Z7AIiMdz-pzgC0SWh9qfkE/edit?tab=t.lwpqe4lgroyz#bookmark=id.p3dk9n24f9ja which was prompted by James's request above. I think it's important that the agent choose the catalog, because in a multi-agent system, the client may not know which subagent is going to reply, so it can't know which catalog to choose.

specification/0.8/docs/a2ui_protocol.md

wrenj · 2025-12-03T13:55:41Z

specification/0.8/docs/a2ui_protocol.md

+  "metadata": {
+    "a2uiClientCapabilities": {
+      "supportedCatalogIds": [
+        "a2ui.org:standard_catalog_0_8_0",


I'm not opposed to using uris here, it could help debugging

I do like the flexible approach with ids though, eg google could embed the rev number google3/learning/agents/moma_catalog@12342322

Yeah, URIs are good because they can be self documenting, even if only used as identifiers. (e.g. https://json-schema.org/draft/2020-12/schema )

+1 to URIs.

I kept the name as 'supportedCatalogIds', but switched to suggesting URIs as a convention, and updated examples. Does that sound okay?

specification/0.8/docs/a2ui_protocol.md

wrenj · 2025-12-03T13:56:49Z

specification/0.8/docs/a2ui_protocol.md

+
+The server receives the client's capabilities and chooses a catalog to use for a specific UI surface. The server specifies its choice in the `beginRendering` message using the `catalogId` field.
+
+- `catalogId` (string, optional): The identifier of the chosen catalog. This ID must be one of the `supportedCatalogIds` or the `catalogId` from one of the `inlineCatalogs` provided by the client.


should we require this? in your example if its not present, what does the client do? just assume the default catalog?

I want to add it as an optional parameter to beginRender in v0.8 and default to standard catalog, to make this change non-breaking. Otherwise all our agents theoretically need updating right away. Filed #193 to make it required for v0.9.

tbh breaking changes are fine, nobody is really using in 1P, and updating the agent samples is easy, not sure about for other teams you work with

Hey that's fair. I guess I want to avoid creating more work trying to get all the renderers in sync for v0.8 too!

wrenj · 2025-12-03T13:57:08Z

specification/0.8/docs/a2ui_protocol.md

+
+- `catalogId` (string, optional): The identifier of the chosen catalog. This ID must be one of the `supportedCatalogIds` or the `catalogId` from one of the `inlineCatalogs` provided by the client.
+
+If the `catalogId` is omitted, the client **MUST** default to the standard catalog for the protocol version (`a2ui.org:standard_catalog_0_8_0`).


is this helpful versus requiring it?

As above - non breaking for now.

specification/0.8/docs/a2ui_protocol.md

wrenj · 2025-12-03T13:59:06Z

specification/0.8/docs/a2ui_protocol.md

 #### Schemas for Developers

-When building an agent, it is recommended to use a resolved schema that includes the specific component catalog you are targeting (e.g., `server_to_client_with_standard_catalog.json`). This provides the LLM with a strict definition of all available components and their properties, leading to more reliable UI generation. The generic `server_to_client.json` is the abstract wire protocol, while the resolved schema is the concrete tool for generation.
+When building an agent, it is recommended to use a resolved schema that includes the specific component catalog you are targeting (e.g., a custom schema combining `server_to_client.json` with your `my-company.com:custom-reporting-catalog-1.2` definition). This provides the LLM with a strict definition of all available components and their properties, leading to more reliable UI generation. The generic `server_to_client.json` is the abstract wire protocol, while the resolved schema is the concrete tool for generation.


add some description of how to build the final catalog

heres the logic i used
https://github.com/google/A2UI/blob/main/a2a_agents/python/adk/samples/rizzcharts/component_catalog_builder.py#L80

Added some example logic.

specification/0.8/docs/a2ui_protocol.md

gspencergoog · 2025-12-03T22:22:09Z

specification/0.8/docs/a2ui_extension_specification.md


-params.acceptsDynamicSchemas: (OPTIONAL) A boolean indicating if the agent can accept a clientUiCapabilities message containing a dynamicCatalog. If omitted, this defaults to false.
+#### Parameter Definitions
+- `params.acceptsInlineCatalogs`: (OPTIONAL) A boolean indicating if the agent can accept an `inlineCatalogs` array in the client's `a2uiClientCapabilities`. If omitted, this defaults to `false`.


I like it as a ~~list.~~ dictionary.

dmandar

LGTM..please follow up with Ava to get this implemented on lit.

jacobsimionato added 2 commits November 24, 2025 13:41

Update v0.8 spec with updated catalog negotiation style

4b6062f

Minor fixes

7d0afbf

jacobsimionato requested a review from wrenj November 24, 2025 03:55

wrenj reviewed Nov 24, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Outdated Show resolved Hide resolved

wrenj reviewed Nov 24, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Outdated Show resolved Hide resolved

wrenj reviewed Nov 24, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Outdated Show resolved Hide resolved

wrenj approved these changes Nov 24, 2025

View reviewed changes

jacobsimionato added 7 commits November 27, 2025 13:27

it reRevert "Minor fixes"

f9a6c8f

This reverts commit 7d0afbf.

Revert "Update v0.8 spec with updated catalog negotiation style"

fcbb93f

This reverts commit 4b6062f.

Merge branch 'main' into custom-catalog

d8eddc6

Update the v0.8 spec with the new custom catalog proposal

af47e4c

Update mention of standard catalog to be not required

c99cc95

Some manual tweaks

a9fa288

Update docs about versioning etc

d83fc18

jacobsimionato requested review from dmandar and gspencergoog November 27, 2025 04:24

wrenj reviewed Dec 3, 2025

View reviewed changes

specification/0.8/docs/a2ui_extension_specification.md Outdated Show resolved Hide resolved

wrenj reviewed Dec 3, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Outdated Show resolved Hide resolved

wrenj reviewed Dec 3, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Outdated Show resolved Hide resolved

wrenj reviewed Dec 3, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Outdated Show resolved Hide resolved

wrenj reviewed Dec 3, 2025

View reviewed changes

dmandar reviewed Dec 3, 2025

View reviewed changes

specification/0.8/docs/a2ui_protocol.md Show resolved Hide resolved

jacobsimionato mentioned this pull request Dec 3, 2025

Ensure custom catalog negotiation API is adapted and updated for v0.9 #193

Closed

Update spec based on feedback

0530929

gspencergoog approved these changes Dec 5, 2025

View reviewed changes

jacobsimionato added 3 commits December 8, 2025 15:18

Merge branch 'main' into custom-catalog

d15eb43

Update angular rizzcharts to use catalogId instead o catalogUri

88e88e6

Update specification to make agent card advertise supported catalogs

3034d16

dmandar approved these changes Dec 8, 2025

View reviewed changes

jacobsimionato added 2 commits December 9, 2025 07:15

Update URI vs ID example

08c5cb6

Merge branch 'main' into custom-catalog

3337ef7

jacobsimionato merged commit b67bdbf into google:main Dec 8, 2025
5 checks passed

gspencergoog mentioned this pull request Dec 8, 2025

Reintroduce createSurface, add evolution guide #226

Merged


		The server receives the client's capabilities and chooses a catalog to use for a specific UI surface. The server specifies its choice in the `beginRendering` message using the `catalogId` field.

		- `catalogId` (string, optional): The identifier of the chosen catalog. This ID must be one of the `supportedCatalogIds` or the `catalogId` from one of the `inlineCatalogs` provided by the client.


		- `catalogId` (string, optional): The identifier of the chosen catalog. This ID must be one of the `supportedCatalogIds` or the `catalogId` from one of the `inlineCatalogs` provided by the client.

		If the `catalogId` is omitted, the client MUST default to the standard catalog for the protocol version (`a2ui.org:standard_catalog_0_8_0`).

Conversation

jacobsimionato commented Nov 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jacobsimionato commented Nov 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gspencergoog Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmandar Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobsimionato Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gspencergoog Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmandar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

gspencergoog Dec 3, 2025 •

edited

Loading

dmandar Dec 3, 2025 •

edited

Loading

jacobsimionato Dec 3, 2025 •

edited

Loading

gspencergoog Dec 3, 2025 •

edited

Loading